<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8">
    
    <title>numpy.digitize &mdash; NumPy v1.18 Manual</title>
    
    <link rel="stylesheet" type="text/css" href="../../_static/css/spc-bootstrap.css">
    <link rel="stylesheet" type="text/css" href="../../_static/css/spc-extend.css">
    <link rel="stylesheet" href="../../_static/scipy.css" type="text/css" >
    <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" >
    <link rel="stylesheet" href="../../_static/graphviz.css" type="text/css" >
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../../',
        VERSION:     '1.18.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../_static/doctools.js"></script>
    <script type="text/javascript" src="../../_static/language_data.js"></script>
    <script type="text/javascript" src="../../_static/js/copybutton.js"></script>
    <link rel="author" title="About these documents" href="../../about.html" >
    <link rel="index" title="Index" href="../../genindex.html" >
    <link rel="search" title="Search" href="../../search.html" >
    <link rel="top" title="NumPy v1.18 Manual" href="../../index.html" >
    <link rel="up" title="Statistics" href="../routines.statistics.html" >
    <link rel="next" title="Test Support (numpy.testing)" href="../routines.testing.html" >
    <link rel="prev" title="numpy.histogram_bin_edges" href="numpy.histogram_bin_edges.html" > 
  </head>
  <body>
<div class="container">
  <div class="top-scipy-org-logo-header" style="background-color: #a2bae8;">
    <a href="../../index.html">
      <img border=0 alt="NumPy" src="../../_static/numpy_logo.png"></a>
    </div>
  </div>
</div>


    <div class="container">
      <div class="main">
        
	<div class="row-fluid">
	  <div class="span12">
	    <div class="spc-navbar">
              
    <ul class="nav nav-pills pull-left">
        <li class="active"><a href="https://numpy.org/">NumPy.org</a></li>
        <li class="active"><a href="https://numpy.org/doc">Docs</a></li>
        
        <li class="active"><a href="../../index.html">NumPy v1.18 Manual</a></li>
        

          <li class="active"><a href="../index.html" >NumPy Reference</a></li>
          <li class="active"><a href="../routines.html" >Routines</a></li>
          <li class="active"><a href="../routines.statistics.html" accesskey="U">Statistics</a></li> 
    </ul>
              
              
    <ul class="nav nav-pills pull-right">
      <li class="active">
        <a href="../../genindex.html" title="General Index"
           accesskey="I">index</a>
      </li>
      <li class="active">
        <a href="../routines.testing.html" title="Test Support (numpy.testing)"
           accesskey="N">next</a>
      </li>
      <li class="active">
        <a href="numpy.histogram_bin_edges.html" title="numpy.histogram_bin_edges"
           accesskey="P">previous</a>
      </li>
    </ul>
              
	    </div>
	  </div>
	</div>
        

	<div class="row-fluid">
      <div class="spc-rightsidebar span3">
        <div class="sphinxsidebarwrapper">
  <h4>Previous topic</h4>
  <p class="topless"><a href="numpy.histogram_bin_edges.html"
                        title="previous chapter">numpy.histogram_bin_edges</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="../routines.testing.html"
                        title="next chapter">Test Support (<code class="xref py py-mod docutils literal notranslate"><span class="pre">numpy.testing</span></code>)</a></p>
<div id="searchbox" style="display: none" role="search">
  <h4>Quick search</h4>
    <div>
    <form class="search" action="../../search.html" method="get">
      <input type="text" style="width: inherit;" name="q" />
      <input type="submit" value="search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
          <div class="span9">
            
        <div class="bodywrapper">
          <div class="body" id="spc-section-body">
            
  <div class="section" id="numpy-digitize">
<h1>numpy.digitize<a class="headerlink" href="#numpy-digitize" title="Permalink to this headline">¶</a></h1>
<dl class="function">
<dt id="numpy.digitize">
<code class="sig-prename descclassname">numpy.</code><code class="sig-name descname">digitize</code><span class="sig-paren">(</span><em class="sig-param">x</em>, <em class="sig-param">bins</em>, <em class="sig-param">right=False</em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/numpy/numpy/blob/v1.18.1/numpy/lib/function_base.py#L4700-L4808"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#numpy.digitize" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the indices of the bins to which each value in input array belongs.</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 18%" />
<col style="width: 26%" />
<col style="width: 56%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p><em class="xref py py-obj">right</em></p></th>
<th class="head"><p>order of bins</p></th>
<th class="head"><p>returned index <em class="xref py py-obj">i</em> satisfies</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">False</span></code></p></td>
<td><p>increasing</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">bins[i-1]</span> <span class="pre">&lt;=</span> <span class="pre">x</span> <span class="pre">&lt;</span> <span class="pre">bins[i]</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">True</span></code></p></td>
<td><p>increasing</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">bins[i-1]</span> <span class="pre">&lt;</span> <span class="pre">x</span> <span class="pre">&lt;=</span> <span class="pre">bins[i]</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">False</span></code></p></td>
<td><p>decreasing</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">bins[i-1]</span> <span class="pre">&gt;</span> <span class="pre">x</span> <span class="pre">&gt;=</span> <span class="pre">bins[i]</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">True</span></code></p></td>
<td><p>decreasing</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">bins[i-1]</span> <span class="pre">&gt;=</span> <span class="pre">x</span> <span class="pre">&gt;</span> <span class="pre">bins[i]</span></code></p></td>
</tr>
</tbody>
</table>
<p>If values in <em class="xref py py-obj">x</em> are beyond the bounds of <em class="xref py py-obj">bins</em>, 0 or <code class="docutils literal notranslate"><span class="pre">len(bins)</span></code> is
returned as appropriate.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><dl class="simple">
<dt><strong>x</strong><span class="classifier">array_like</span></dt><dd><p>Input array to be binned. Prior to NumPy 1.10.0, this array had to
be 1-dimensional, but can now have any shape.</p>
</dd>
<dt><strong>bins</strong><span class="classifier">array_like</span></dt><dd><p>Array of bins. It has to be 1-dimensional and monotonic.</p>
</dd>
<dt><strong>right</strong><span class="classifier">bool, optional</span></dt><dd><p>Indicating whether the intervals include the right or the left bin
edge. Default behavior is (right==False) indicating that the interval
does not include the right edge. The left bin end is open in this
case, i.e., bins[i-1] &lt;= x &lt; bins[i] is the default behavior for
monotonically increasing bins.</p>
</dd>
</dl>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><dl class="simple">
<dt><strong>indices</strong><span class="classifier">ndarray of ints</span></dt><dd><p>Output array of indices, of same shape as <em class="xref py py-obj">x</em>.</p>
</dd>
</dl>
</dd>
<dt class="field-odd">Raises</dt>
<dd class="field-odd"><dl class="simple">
<dt><strong>ValueError</strong></dt><dd><p>If <em class="xref py py-obj">bins</em> is not monotonic.</p>
</dd>
<dt><strong>TypeError</strong></dt><dd><p>If the type of the input is complex.</p>
</dd>
</dl>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="numpy.bincount.html#numpy.bincount" title="numpy.bincount"><code class="xref py py-obj docutils literal notranslate"><span class="pre">bincount</span></code></a>, <a class="reference internal" href="numpy.histogram.html#numpy.histogram" title="numpy.histogram"><code class="xref py py-obj docutils literal notranslate"><span class="pre">histogram</span></code></a>, <a class="reference internal" href="numpy.unique.html#numpy.unique" title="numpy.unique"><code class="xref py py-obj docutils literal notranslate"><span class="pre">unique</span></code></a>, <a class="reference internal" href="numpy.searchsorted.html#numpy.searchsorted" title="numpy.searchsorted"><code class="xref py py-obj docutils literal notranslate"><span class="pre">searchsorted</span></code></a></p>
</div>
<p class="rubric">Notes</p>
<p>If values in <em class="xref py py-obj">x</em> are such that they fall outside the bin range,
attempting to index <em class="xref py py-obj">bins</em> with the indices that <a class="reference internal" href="#numpy.digitize" title="numpy.digitize"><code class="xref py py-obj docutils literal notranslate"><span class="pre">digitize</span></code></a> returns
will result in an IndexError.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.10.0.</span></p>
</div>
<p><em class="xref py py-obj">np.digitize</em> is  implemented in terms of <em class="xref py py-obj">np.searchsorted</em>. This means
that a binary search is used to bin the values, which scales much better
for larger number of bins than the previous linear search. It also removes
the requirement for the input array to be 1-dimensional.</p>
<p>For monotonically _increasing_ <em class="xref py py-obj">bins</em>, the following are equivalent:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">np</span><span class="o">.</span><span class="n">digitize</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">bins</span><span class="p">,</span> <span class="n">right</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="n">np</span><span class="o">.</span><span class="n">searchsorted</span><span class="p">(</span><span class="n">bins</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">side</span><span class="o">=</span><span class="s1">&#39;left&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>Note that as the order of the arguments are reversed, the side must be too.
The <a class="reference internal" href="numpy.searchsorted.html#numpy.searchsorted" title="numpy.searchsorted"><code class="xref py py-obj docutils literal notranslate"><span class="pre">searchsorted</span></code></a> call is marginally faster, as it does not do any
monotonicity checks. Perhaps more importantly, it supports all dtypes.</p>
<p class="rubric">Examples</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mf">0.2</span><span class="p">,</span> <span class="mf">6.4</span><span class="p">,</span> <span class="mf">3.0</span><span class="p">,</span> <span class="mf">1.6</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">bins</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mf">0.0</span><span class="p">,</span> <span class="mf">1.0</span><span class="p">,</span> <span class="mf">2.5</span><span class="p">,</span> <span class="mf">4.0</span><span class="p">,</span> <span class="mf">10.0</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">inds</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">digitize</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">bins</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">inds</span>
<span class="go">array([1, 4, 3, 2])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">n</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">x</span><span class="o">.</span><span class="n">size</span><span class="p">):</span>
<span class="gp">... </span>  <span class="nb">print</span><span class="p">(</span><span class="n">bins</span><span class="p">[</span><span class="n">inds</span><span class="p">[</span><span class="n">n</span><span class="p">]</span><span class="o">-</span><span class="mi">1</span><span class="p">],</span> <span class="s2">&quot;&lt;=&quot;</span><span class="p">,</span> <span class="n">x</span><span class="p">[</span><span class="n">n</span><span class="p">],</span> <span class="s2">&quot;&lt;&quot;</span><span class="p">,</span> <span class="n">bins</span><span class="p">[</span><span class="n">inds</span><span class="p">[</span><span class="n">n</span><span class="p">]])</span>
<span class="gp">...</span>
<span class="go">0.0 &lt;= 0.2 &lt; 1.0</span>
<span class="go">4.0 &lt;= 6.4 &lt; 10.0</span>
<span class="go">2.5 &lt;= 3.0 &lt; 4.0</span>
<span class="go">1.0 &lt;= 1.6 &lt; 2.5</span>
</pre></div>
</div>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mf">1.2</span><span class="p">,</span> <span class="mf">10.0</span><span class="p">,</span> <span class="mf">12.4</span><span class="p">,</span> <span class="mf">15.5</span><span class="p">,</span> <span class="mf">20.</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">bins</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">15</span><span class="p">,</span> <span class="mi">20</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">digitize</span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="n">bins</span><span class="p">,</span><span class="n">right</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="go">array([1, 2, 3, 4, 4])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">digitize</span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="n">bins</span><span class="p">,</span><span class="n">right</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="go">array([1, 3, 3, 4, 5])</span>
</pre></div>
</div>
</dd></dl>

</div>


          </div>
        </div>
          </div>
        </div>
      </div>
    </div>

    <div class="container container-navbar-bottom">
      <div class="spc-navbar">
        
      </div>
    </div>
    <div class="container">
    <div class="footer">
    <div class="row-fluid">
    <ul class="inline pull-left">
      <li>
        &copy; Copyright 2008-2019, The SciPy community.
      </li>
      <li>
      Last updated on Feb 20, 2020.
      </li>
      <li>
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.4.2.
      </li>
    </ul>
    </div>
    </div>
    </div>
  </body>
</html>